<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.10.0"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Direct3D 12 Memory Allocator: Custom memory pools</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="clipboard.js"></script>
<script type="text/javascript" src="cookie.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">Direct3D 12 Memory Allocator
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.10.0 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>

<div id="nav-path" class="navpath">
  <ul>
<li class="navelem"><a class="el" href="index.html">D3D12 Memory Allocator</a></li>  </ul>
</div>
</div><!-- top -->
<div><div class="header">
  <div class="headertitle"><div class="title">Custom memory pools</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>A "pool" is a collection of memory blocks that share certain properties. Allocator creates 3 default pools: for <code>D3D12_HEAP_TYPE_DEFAULT</code>, <code>UPLOAD</code>, <code>READBACK</code>. A default pool automatically grows in size. Size of allocated blocks is also variable and managed automatically. Typical allocations are created in these pools. You can also create custom pools.</p>
<h1><a class="anchor" id="custom_pools_usage"></a>
Usage</h1>
<p>To create a custom pool, fill in structure <a class="el" href="struct_d3_d12_m_a_1_1_p_o_o_l___d_e_s_c.html" title="Parameters of created D3D12MA::Pool object. To be used with D3D12MA::Allocator::CreatePool.">D3D12MA::POOL_DESC</a> and call function <a class="el" href="class_d3_d12_m_a_1_1_allocator.html#aac7b1f6bf53cbf4c4ce2264cb72ca515" title="Creates custom pool.">D3D12MA::Allocator::CreatePool</a> to obtain object <a class="el" href="class_d3_d12_m_a_1_1_pool.html" title="Custom memory pool.">D3D12MA::Pool</a>. Example:</p>
<div class="fragment"><div class="line">POOL_DESC poolDesc = {};</div>
<div class="line">poolDesc.HeapProperties.Type = D3D12_HEAP_TYPE_DEFAULT;</div>
<div class="line"><span class="comment">// These flags are optional but recommended.</span></div>
<div class="line">poolDesc.Flags = <a class="code hl_enumvalue" href="namespace_d3_d12_m_a.html#a919d8545365d6b7209a964f2b99936d1acc379a89755438c0f76667783b778baa">D3D12MA::POOL_FLAG_MSAA_TEXTURES_ALWAYS_COMMITTED</a>;</div>
<div class="line">poolDesc.HeapFlags = D3D12_HEAP_FLAG_CREATE_NOT_ZEROED;</div>
<div class="line"> </div>
<div class="line">Pool* pool;</div>
<div class="line">HRESULT hr = allocator-&gt;CreatePool(&amp;poolDesc, &amp;pool);</div>
<div class="ttc" id="anamespace_d3_d12_m_a_html_a919d8545365d6b7209a964f2b99936d1acc379a89755438c0f76667783b778baa"><div class="ttname"><a href="namespace_d3_d12_m_a.html#a919d8545365d6b7209a964f2b99936d1acc379a89755438c0f76667783b778baa">D3D12MA::POOL_FLAG_MSAA_TEXTURES_ALWAYS_COMMITTED</a></div><div class="ttdeci">@ POOL_FLAG_MSAA_TEXTURES_ALWAYS_COMMITTED</div><div class="ttdoc">Optimization, allocate MSAA textures as committed resources always.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:842</div></div>
</div><!-- fragment --><p>To allocate resources out of a custom pool, only set member <a class="el" href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#ab06b85f3cf3254f855b29264477e3934" title="Custom pool to place the new resource in. Optional.">D3D12MA::ALLOCATION_DESC::CustomPool</a>. Example:</p>
<div class="fragment"><div class="line">ALLOCATION_DESC allocDesc = {};</div>
<div class="line">allocDesc.CustomPool = pool;</div>
<div class="line"> </div>
<div class="line">D3D12_RESOURCE_DESC resDesc = ...</div>
<div class="line">Allocation* alloc;</div>
<div class="line">hr = allocator-&gt;CreateResource(&amp;allocDesc, &amp;resDesc,</div>
<div class="line">    D3D12_RESOURCE_STATE_GENERIC_READ, NULL, &amp;alloc, IID_NULL, NULL);</div>
</div><!-- fragment --><p>All allocations must be released before releasing the pool. The pool must be released before relasing the allocator.</p>
<div class="fragment"><div class="line">alloc-&gt;Release();</div>
<div class="line">pool-&gt;Release();</div>
</div><!-- fragment --><h1><a class="anchor" id="custom_pools_features_and_benefits"></a>
Features and benefits</h1>
<p>While it is recommended to use default pools whenever possible for simplicity and to give the allocator more opportunities for internal optimizations, custom pools may be useful in following cases:</p>
<ul>
<li>To keep some resources separate from others in memory.</li>
<li>To keep track of memory usage of just a specific group of resources. Statistics can be queried using <a class="el" href="class_d3_d12_m_a_1_1_pool.html#ad07999ac5dc8f0c63187afd45d551910" title="Retrieves detailed statistics of the custom pool that are slower to calculate.">D3D12MA::Pool::CalculateStatistics</a>.</li>
<li>To use specific size of a memory block (<code>ID3D12Heap</code>). To set it, use member <a class="el" href="struct_d3_d12_m_a_1_1_p_o_o_l___d_e_s_c.html#af7284cc51a8ed5b551075584256de23c" title="Size of a single heap (memory block) to be allocated as part of this pool, in bytes....">D3D12MA::POOL_DESC::BlockSize</a>. When set to 0, the library uses automatically determined, variable block sizes.</li>
<li>To reserve some minimum amount of memory allocated. To use it, set member <a class="el" href="struct_d3_d12_m_a_1_1_p_o_o_l___d_e_s_c.html#a6f10db3911a3bea1becfc9a0dfa5bac8" title="Minimum number of heaps (memory blocks) to be always allocated in this pool, even if they stay empty....">D3D12MA::POOL_DESC::MinBlockCount</a>.</li>
<li>To limit maximum amount of memory allocated. To use it, set member <a class="el" href="struct_d3_d12_m_a_1_1_p_o_o_l___d_e_s_c.html#abbce3a99f253928f9c3c09fa16015f9e" title="Maximum number of heaps (memory blocks) that can be allocated in this pool. Optional.">D3D12MA::POOL_DESC::MaxBlockCount</a>.</li>
<li>To use extended parameters of the D3D12 memory allocation. While resources created from default pools can only specify <code>D3D12_HEAP_TYPE_DEFAULT</code>, <code>UPLOAD</code>, <code>READBACK</code>, a custom pool may use non-standard <code>D3D12_HEAP_PROPERTIES</code> (member <a class="el" href="struct_d3_d12_m_a_1_1_p_o_o_l___d_e_s_c.html#a06e06813bcb5206e9f7a8b0564bf1d6a" title="The parameters of memory heap where allocations of this pool should be placed.">D3D12MA::POOL_DESC::HeapProperties</a>) and <code>D3D12_HEAP_FLAGS</code> (<a class="el" href="struct_d3_d12_m_a_1_1_p_o_o_l___d_e_s_c.html#a3795956e4fbfe7c3a23546e02e5d28dc" title="Heap flags to be used when allocating heaps of this pool.">D3D12MA::POOL_DESC::HeapFlags</a>), which is useful e.g. for cross-adapter sharing or UMA (see also <a class="el" href="class_d3_d12_m_a_1_1_allocator.html#a9e742884bd45dd7f01193d13fcd05af0" title="Returns true if D3D12_FEATURE_DATA_ARCHITECTURE1::UMA was found to be true.">D3D12MA::Allocator::IsUMA</a>).</li>
</ul>
<p>New versions of this library support creating <b>committed allocations in custom pools</b>. It is supported only when <a class="el" href="struct_d3_d12_m_a_1_1_p_o_o_l___d_e_s_c.html#af7284cc51a8ed5b551075584256de23c" title="Size of a single heap (memory block) to be allocated as part of this pool, in bytes....">D3D12MA::POOL_DESC::BlockSize</a> = 0. To use this feature, set <a class="el" href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#ab06b85f3cf3254f855b29264477e3934" title="Custom pool to place the new resource in. Optional.">D3D12MA::ALLOCATION_DESC::CustomPool</a> to the pointer to your custom pool and <a class="el" href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#a92dec49b788a334fc91c55340dfbace6" title="Flags.">D3D12MA::ALLOCATION_DESC::Flags</a> to <a class="el" href="namespace_d3_d12_m_a.html#abbad31a7e0b3d09d77f3fb704b77645ea661a5472dba3dcecc5a2cc92afd25675">D3D12MA::ALLOCATION_FLAG_COMMITTED</a>. Example:</p>
<div class="fragment"><div class="line">ALLOCATION_DESC allocDesc = {};</div>
<div class="line">allocDesc.CustomPool = pool;</div>
<div class="line">allocDesc.Flags = ALLOCATION_FLAG_COMMITTED;</div>
<div class="line"> </div>
<div class="line">D3D12_RESOURCE_DESC resDesc = ...</div>
<div class="line">Allocation* alloc;</div>
<div class="line">ID3D12Resource* res;</div>
<div class="line">hr = allocator-&gt;CreateResource(&amp;allocDesc, &amp;resDesc,</div>
<div class="line">    D3D12_RESOURCE_STATE_GENERIC_READ, NULL, &amp;alloc, IID_PPV_ARGS(&amp;res));</div>
</div><!-- fragment --><p>This feature may seem unnecessary, but creating committed allocations from custom pools may be useful in some cases, e.g. to have separate memory usage statistics for some group of resources or to use extended allocation parameters, like custom <code>D3D12_HEAP_PROPERTIES</code>, which are available only in custom pools. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.10.0
</small></address>
</body>
</html>
